Workflow Retry Template

The Workflow Retry template demonstrates how BindAI can retry failed workflow-node execution before ultimately failing the workflow. Retry behavior is implemented by the workflow executor. When a node raises an exception and a retry policy is configured, the executor re-executes that node until it succeeds or the configured attempt limit is reached. The current implementation provides basic executor-level retry handling. Retry delays and exponential backoff are not yet applied.

Purpose

This template demonstrates how to:

Configure a retry policy
Retry failed node execution
Limit repeated attempts
Continue workflow execution after successful recovery
Handle final workflow failure
Understand the limitations of the current retry implementation

Workflow Structure

Retry is handled by the executor rather than by a separate workflow branch. Conceptually:

Workflow
   |
   v
Operation
   |
   +---- Success ----> Continue
   |
   +---- Exception
            |
            v
        Retry Policy
            |
            v
         Try Again

The retry mechanism operates around the execution of the current node. It does not require an additional workflow node to represent each retry.

RetryPolicy

The retry configuration is represented by RetryPolicy:

from bindai_workflow.retry import RetryPolicy

policy = RetryPolicy(
    max_attempts=3,
    delay_seconds=5,
    exponential_backoff=True,
)

The policy contains three fields:

Field	Default	Current behavior
`max_attempts`	`3`	Used by the executor to determine when retries are exhausted
`delay_seconds`	`5`	Defined but not applied by the executor
`exponential_backoff`	`True`	Defined but not applied by the executor

The executor uses max_attempts when deciding whether to retry a failed node. The existence of a policy field does not mean that the corresponding behavior is implemented.

Retry Policy Defaults

RetryPolicy is a dataclass with these defaults:

RetryPolicy(
    max_attempts=3,
    delay_seconds=5,
    exponential_backoff=True,
)

The policy object stores configuration values. The workflow executor interprets the policy during node execution. Currently, only max_attempts affects retry decisions. The policy does not itself execute nodes, wait between attempts, or calculate backoff intervals.

Execution Flow

When a node executes successfully:

Execute Node
     |
     v
  Success
     |
     v
Continue Workflow

When the node raises an exception and a retry policy exists:

Execute Node
     |
     v
  Exception
     |
     v
Increment Failure Counter
     |
     v
Attempt Limit Reached?
     |
     +---- No ----> Retry Immediately
     |
     +---- Yes ---> Workflow Failure

The executor repeats the same node execution until it succeeds or the attempt limit is reached. Retries occur immediately; the configured delay and exponential-backoff settings are not currently applied.

Retry Lifecycle

For:

max_attempts=3

the execution can look like this:

Attempt 1
   |
 Failure
   |
Attempt 2
   |
 Failure
   |
Attempt 3
   |
 Success
   |
Continue Workflow

If all three attempts fail:

Attempt 3
   |
 Failure
   |
Workflow Failure

Here, max_attempts represents the maximum number of failed attempts handled by this retry mechanism before failure, assuming the exception reaches the retry handler each time. It is not three additional retries after an initial attempt. For example, with max_attempts=3, the executor can attempt the node up to three times. If the first attempt fails and the second succeeds, execution continues after the second attempt.

Retry Counter

The workflow context tracks the current retry attempt using:

context.retry_attempt

Before executing a workflow node, the executor resets the counter:

context.retry_attempt = 0

When the node raises an exception and a retry policy exists, the executor increments it:

context.retry_attempt += 1

The executor then compares the counter with:

context.retry_policy.max_attempts

If the counter reaches the configured maximum, the executor returns a workflow failure. Otherwise, it continues the execution loop and retries the node. After a successful node execution, the counter is reset.

Successful Recovery

A retry can recover from a temporary node failure. For example:

Attempt 1
   |
Exception
   |
Retry Immediately
   |
Attempt 2
   |
Success
   |
Next Workflow Node

After the node succeeds, the executor resets:

context.retry_attempt = 0

The workflow can then continue normally. Successful recovery depends on the node succeeding on a subsequent attempt. The retry mechanism does not guarantee that a transient failure will resolve.

Retry Without a Policy

If a node raises an exception and no retry policy is configured:

Execute
   |
Exception
   |
No Retry Policy
   |
Workflow Failure

The executor invokes its normal failure handling. There is no automatic retry when context.retry_policy is None.

Retry Limit

The max_attempts field controls the limit used by the executor. For example:

RetryPolicy(
    max_attempts=3,
)

allows up to three attempts of the node execution handled by the retry loop:

Attempt 1
Attempt 2
Attempt 3

If all three attempts fail, the executor invokes normal workflow failure handling. Choose this limit deliberately, particularly when a node calls an external service or performs an operation with side effects.

Retry Behavior in the Executor

The executor follows this simplified pattern:

while True:
    try:
        node.execute(context)
        context.retry_attempt = 0
        return

    except Exception as ex:
        policy = context.retry_policy

        if policy is None:
            fail()

        context.retry_attempt += 1

        if context.retry_attempt >= policy.max_attempts:
            fail()

        # Retry immediately; no delay or backoff is applied.

This is a simplified illustration of the retry logic, not a complete copy of the executor implementation. The real executor also performs workflow bookkeeping and failure handling. The retry is implemented within the node execution loop. No additional workflow node is required to represent the retry.

Delay Configuration

The retry policy contains:

delay_seconds=5

However, the current executor does not sleep for this duration. For example:

RetryPolicy(
    max_attempts=3,
    delay_seconds=5,
)

does not currently produce a five-second delay between attempts. The field is defined in the policy, but it is not applied by the executor. Retries therefore occur immediately.

Exponential Backoff

The policy also contains:

exponential_backoff=True

However, the current executor does not calculate or apply exponential backoff. The current behavior remains:

Failure
   |
Immediate Retry
   |
Failure
   |
Immediate Retry

The exponential_backoff field is not currently active. Do not rely on it to increase the interval between retry attempts.

Exception Handling

The current retry mechanism catches exceptions raised during node execution. There is no exception-type filter in the current RetryPolicy. When a policy is configured, exceptions caught by this handler are subject to the same retry-attempt logic regardless of exception class. There is no current configuration such as:

retry_on=[TimeoutError, ConnectionError]

in RetryPolicy. Applications should not assume that only transient or explicitly selected exception types will be retried.

Retry vs Loop

Retry and Loop solve different problems.

Retry	Loop
Responds to caught node execution exceptions	Repeats workflow logic according to a loop predicate
Re-executes failed node work	Intentionally repeats workflow routing
Implemented by the executor	Implemented by workflow loop functionality
Uses `RetryPolicy`	Uses a loop predicate
Stops on success or an exhausted attempt limit	Stops when its loop condition no longer permits iteration

Use Retry for failure recovery. Use Loop for intentional iteration.

Retry and Parallel Workflows

Retry behavior is implemented by the workflow executor rather than by ParallelNode itself. Conceptually, a workflow might contain parallel branches:

             Parallel
             /      \
            v        v
       Branch A    Branch B
           |          |
           v          v
         Node       Node
           |          |
           v          v
       Execution   Execution
        failure     failure

Whether retry behaves as expected within a particular parallel workflow depends on how that workflow is executed and how its node failures propagate. Do not assume that retry configuration changes parallel-join semantics or guarantees recovery of an entire parallel branch. Verify those interactions for the workflow structure being used.

Retry and Timeout

Retry and timeout policies serve different purposes:

Retry handles exceptions raised during node execution.
Timeout checks elapsed workflow time during execution.

The current timeout implementation checks elapsed time between node executions. It does not interrupt a node that is already running. Consequently, retry and timeout should not be treated as independent guarantees that bound the total execution time. Immediate retries may continue within the node execution loop before the executor reaches its next timeout check. Also note that the timeout policy’s fail_workflow field is not currently used by the executor.

Final Failure

When the retry limit is reached, the executor invokes its normal workflow failure handling. That failure path is responsible for recording the failure and producing an unsuccessful workflow result. The exact persistence, event, and compensation behavior depends on the executor’s failure-handling implementation. Retry itself does not provide durable job recovery, distributed execution, or a guarantee that external side effects can be undone. If your application depends on specific failure events, persistence behavior, or compensation callbacks, verify those behaviors against the relevant runtime implementation.

Failure Without Retries

A node failure without a retry policy follows the normal failure path:

Node Execution
      |
      v
Exception
      |
      v
No Retry Policy
      |
      v
Workflow Failure

The executor does not attempt the node again when no retry policy is configured.

Example Workflow

A conceptual retry workflow looks like:

Start
  |
  v
Call External Service
  |
  v
Node Execution Exception?
 /                  \
No                  Yes
|                    |
v                    v
Continue        Check Attempt Limit
                    /       \
              Attempts     Limit
              remain      reached
                 |            |
                 v            v
           Retry Immediately  Fail

The retry behavior is provided by the executor rather than by additional workflow nodes.

Safe Retry Considerations

Retrying a node means executing its operation again. This is important for operations that have side effects. For example, these operations may not always be safe to repeat:

Sending an email
Creating a payment
Creating a database record
Submitting an order
Calling an external API that changes state

An operation might succeed remotely even if the local workflow receives an exception before obtaining the result. Retrying it could then repeat the side effect. A retry policy should therefore be used deliberately. For external operations, consider idempotency controls and application- or tool-level error handling.

Best Practices

Set max_attempts deliberately.
Understand that the limit controls the number of attempts handled by the retry loop.
Retry operations only when repeating them is safe.
Consider idempotency for external side effects.
Do not assume delay_seconds causes a delay.
Do not assume exponential_backoff is active.
Remember that the current policy does not filter exception types.
Do not treat workflow timeout as a hard interruption of a running node.
Test both successful recovery and exhausted retries.
Verify failure and compensation behavior for workflows that depend on it.

The Retry template may be relevant to workflows that also use:

08.3 workflow-loop.md
08.4 workflow-parallel.md
08.7 workflow-timeout.md
08.8 workflow-schedule.md

Retry can be part of a larger workflow structure because its behavior is implemented by the workflow executor. The interactions between these features should be verified for the particular workflow configuration.

Summary

The Workflow Retry template demonstrates executor-level retry handling for failed workflow-node execution. When a node raises an exception and a RetryPolicy is configured, BindAI retries the node until it succeeds or the configured attempt limit is reached. The current RetryPolicy contains:

max_attempts
delay_seconds
exponential_backoff

Only max_attempts currently affects retry execution. Retries happen immediately, and delay, exponential backoff, and exception-type filtering are not implemented. The current implementation provides basic attempt-limit handling, which can be extended later with delayed retries, backoff, and more selective retry behavior.

Getting Started

Core

Tools

Memory

Knowledge

Workflows

Projects

Templates

Connections

API Reference

Automation

Roadmap

08.6 workflow retry

Workflow Retry Template

Purpose

Workflow Structure

RetryPolicy

Retry Policy Defaults

Execution Flow

Retry Lifecycle

Retry Counter

Successful Recovery

Retry Without a Policy

Retry Limit

Retry Behavior in the Executor

Delay Configuration

Exponential Backoff

Exception Handling

Retry vs Loop

Retry and Parallel Workflows

Retry and Timeout

Final Failure

Failure Without Retries

Example Workflow

Safe Retry Considerations

Best Practices

Summary

​Workflow Retry Template

​Purpose

​Workflow Structure

​RetryPolicy

​Retry Policy Defaults

​Execution Flow

​Retry Lifecycle

​Retry Counter

​Successful Recovery

​Retry Without a Policy

​Retry Limit

​Retry Behavior in the Executor

​Delay Configuration

​Exponential Backoff

​Exception Handling

​Retry vs Loop

​Retry and Parallel Workflows

​Retry and Timeout

​Final Failure

​Failure Without Retries

​Example Workflow

​Safe Retry Considerations

​Best Practices

​Related Templates

​Summary

Workflow Retry Template

Purpose

Workflow Structure

RetryPolicy

Retry Policy Defaults

Execution Flow

Retry Lifecycle

Retry Counter

Successful Recovery

Retry Without a Policy

Retry Limit

Retry Behavior in the Executor

Delay Configuration

Exponential Backoff

Exception Handling

Retry vs Loop

Retry and Parallel Workflows

Retry and Timeout

Final Failure

Failure Without Retries

Example Workflow

Safe Retry Considerations

Best Practices

Related Templates

Summary